TOS Silver 2000

home *** CD-ROM | disk | FTP | other *** search

/ TOS Silver 2000 / TOS Silver 2000.iso / Tools / ZCONTROL.25A / ENGLISH / ZCONTROL.TXT < prev next >

Wrap

Text File | 1995-12-27 | 25.3 KB | 860 lines

The Manual to zControl 0.23 December 27, 1995 by Ralf Zimmermann Am Ruhwehr 35 D-65207 Wiesbaden dl1fdt@amsat.org Contents ======== 1 This Version 1.1 English Version 2 Orlando/Florida 3 Copyright 3.1 Shareware 3.2 UK Register 3.3 Price List 4 Motivation 5 Installation 6 Operating the program 6.1 Main dialogue 6.2 Popup-Dialogue 'Options' 6.3 Settings 6.4 Choice Modules 6.5 Select a module 6.6 Activate a module 6.7 Keyboard Handling 6.8 Command Line Parameters for zControl 6.8.1 Anwendung anmelden 6.8.2 AV Protocol 6.8.3 Drag&Drop 6.9 Iconify 7 The INF File 7.1 Debug Function 7.2 Where will the INF file be searched? 8 Undocumented Functions 8.1 KONFIG.CPX 8.2 LINK_CPX.CPX 8.3 DFREE.CPX Appendix ======== A The Format of the INF File B The Format of the FILESORT.SYS file C Sources of supply D Thanks E Troubleshooting F History 1 This Version ============== This program is not finished! I'd like to describe it as a *very good tested* Beta-Version. At this time I have not the time to implement all the things I'd like to see in the program. And I can't say when I will have the final version. Within the last few months some people have been asking when zControl would come. So I decided to release this version to the public - the program works without major problems. As soon as I have some more time I will release a new version! 'Without major problems' means: In this version zControl runs as ACC only under multitasking systems. As soon as you try to start it under Single-TOS, such as TOS 3.06, as a ACC you get some bombs. Until now I didn't know what the problem is and therefore I can't change it. I am using MagiC!3 and MagicMac and have no problems with zControl. So let's hope for a magic idea for the future. From then on zControl will be fully usable for all users, even these with Single- Tasking systems. As an ACC under Single-TOS you get a warning message while booting. No CPX modules will be loaded. You can load the modules afterwards. If you get problems with this procedure I would appreciate a bug report to me. Please tell me something about your configuration: Computer, memory, operating system, HD-driver, AUTO-folder- programs... Since version 0.22 there is the option SINGLELOAD. With it, zControl works normal under Single-TOS - the modules will be loaded. This option is for testing purposes. In chapter "The Format of the INF File", you can read how to use it. *Whoever tries this option under Single-TOS, should write me a report via email.* Here in Florida I don't have a computer with Single-TOS, this is why I depend on those reports. 1.1 English Version ------------------- Version 0.20 of zControl had an English documentation, the version 0.21 now can run in English (and German of course). In the future, maybe, there will be other languages supported. Please note: There is an German version of this manual. 2 Orlando/Florida ================= From end of July 95 to mid of March 96 I am in Orlando/Florida. I am finishing my studies here. Although Orlando is a very nice place to stay - I can not access all the Atari equipment I have at home in Germany. This results in a restricted ability to test this program. I am sorry for that. 3 Copyright =========== zControl is a Shareware program by Ralf Zimmermann Am Ruhwehr 35 65207 Wiesbaden Germany MausNet : Ralf Zimmermann @ OF2 internet : dl1fdt@amsat.org PacketRadio : DL1FDT@DB0GV Bank Account: Nassauische Sparkasse Wiesbaden Bank code number 510 500 15 Account number 1010 299 72 The fastest way to reach the author should be to use the email! 3.1 Shareware ------------- This program is distributed as Shareware. This means you can test this program without any restrictions. By testing I consider 3 weeks. After this time you should know if you want to use this program or not. Which restrictions does this program have in the public version? *- None -* There is no other version of zControl! All features of this program are *not* restricted! Therefore zControl is a *real* representation of Shareware. By registering the program you pay for a program that you already have and that you were able to test thoroughly. I think there is no fairer way to distribute software. I hope it works. If you like the program and want to use it in the future, you have to register it. This can be done by paying the Shareware fee of DM10 to the author through remittance, cash or crossed cheque, or sending the registration fee too the appropriate support site. Please note the following: If you use a Shareware program without registering, you are using an unauthorized copy! Standard-Disclaimer: This program was made carefully. The author is not responsible for any damages that originate from the usage or non-usage of zControl. 3.2 UK Register --------------- UK users may register for zControl via CyberSTrider, the shareware support scheme run by Denesh Bhabuta. The UK shareware fee for zControl currently stands at 6 Pounds Sterling, which entitles you to ∙ A printed labelled Master Disk with the latest version of zControl, plus a selection of other shareware supported by Denesh. ∙ Free e-mail, post and telephone support ∙ Free update service (as long as the registration fee does not go up, or it becomes commercial) If you use zControl, then you must register. Make cheques, postal orders, international money orders, and eurocheques payable to DENESH BHABUTA, for the sum of 6 Pounds Sterling (overseas users please add 1 pound), and send with your details to: CyberSTrider 203 Parr Lane Unsworth Bury Lancashire BL9 8JW England E-mail: dbhabuta@cix.compulink.co.uk danny@micros.hensa.ac.uk *Free Update Service* Registered users may benefit from the free update service by sending an unlabelled blank floppy disk and stamped self addressed envelope to Denesh at the above address. 3.3 Price List -------------- If you register zControl directly at the author, the price to register one user presently is: DM 10,- 4 Motivation ============ Since TOS 2.00 you get the XCONTROL.ACC from Atari. It is the environment for CPX modules. These are modules for configurating your computer or programs. There are for example modules to configure the serial interface, the keyboard or the printer. Some modules come with their own CPX modules. All CPX modules have the file extension '.CPX'. The modules do not run without a modular Control Panel (zControl or XControl)! We all know that XControl has some nasty bugs. That was the beginning of my idea to build an alternative. *zControl is made to be this alternative.* It loads the same CPX modules as XControl and behaves almost compatible, as far as the documentation recommends that. The advantages in contrast to XControl are quite obvious: ∙ zControl will be developed in the future, all known bugs will be removed. ∙ zControl supports following protocols: - Drag&Drop - Iconify - AV-protocol This means that the program fits perfectly into modern user interfaces. ∙ zControl enables you to run up to four different modules at the same time! Each module runs in its own window. ∙ zControl can be controlled through the keyboard. ∙ zControl has some more useful features, you may have looked for. 5 Installation ============== Copy the file ZCONTROL.ACC to the root directory of your boot drive. Generate a folder named CPX and copy all your CPX modules into that folder. The folder can be named differently. Then reboot. Now call the program through the entry in the menu. Click on the button 'Options' on the main dialog. Choose 'Settings...' in the popup dialog you get. You get a file selector dialog. Please show zControl the folder from which the modules should be loaded in future. Usually this should be the folder C:\CPX\ Click on the button 'Save' and confirm the security dialog. After that, zControl should search the CPX modules in the correct folder while starting. Under multitasking systems you can run zControl as an application. Change the file extension from .ACC to .APP or .PRG and you can use zControl as a normal program. 6 Operating the program ======================= In the following pages you will learn how to operate the program. 6.1 Main dialogue ----------------- After entering the program you get the main dialogue. You can see which programs are loaded and therefor are available. If more modules were found than fit into the dialogue (as usual), you can scroll to the other modules by using the vertical slider to the right. ATTENTION: The beta version of zControl has a scrolling window name. This should remind you that this is only a beta version. As soon as the final version is finished this 'feature' will disappear. 6.2 Popup-Dialogue 'Options' ---------------------------- ∙ Info... You can get a short copyright information about this program. You will find the version number in this dialogue. ∙ Settings... You get to an dialogue where you can configure the program. ∙ Open CPX... You can activate a selected module with this popup entry as if you make a double click on the module entry. ∙ CPX Info... You can get some information about the selected module. ∙ Remove CPX... The selected module will be removed from the memory. 6.3 Settings ------------ In this dialogue you can ∙ reload CPX modules. ∙ switch to the dialogue 'Choice Modules'. ∙ change the number of CPX entries on the main dialogue. ∙ change the language used by zControl. Right now English and German are available. ∙ change the folder in which zControl looks for the CPX modules. 6.4 Choice Modules ------------------ In this dialogue you can change the selection of modules that will be loaded next time by zControl. Active modules in the list are marked with a hook. You can change the status of a module (active/inactive) through a click on the entry. Note: De/activating is made by changing the file extension of the module. Active modules have the extension '.CPX', inactive modules have the extension '.CPZ'. 6.5 Select a module ------------------- You can select a module easily by clicking with the left mouse button on the module entry. The selection is visible through the inverted display of that entry. If you have a selected module, you get more options in the 'Options' popup dialog. 6.6 Activate a module --------------------- You can activate a module through ∙ a double click with the mouse on the entry. ∙ pressing the Return key while the entry is selected. (see Keyboard Handling) ∙ a VA_START message. ∙ a Drag&Drop message. Each activated module has it's own window. Presently you can have up to four CPX windows at the same time. This number is arbitrary and may be changed in future versions. 6.7 Keyboard Handling --------------------- In the main dialogue zControl can be controlled via the keyboard: Cursor Up - Moves the selection bar one entry to the top. - If there is no selection before, the lowest entry will be selected. Cursor Down - Moves the selection bar one entry down. - If there is no selection before, the highest entry will be selected. Shift Cursor - Moves the selection bar one page. Return Enter - If there is a selection, the selected module will be activated. - If there is no selection, the window will be closed. Esc - If a selection exists, it will be removed. Control-U Control-Q - The window will be closed. Control-Alternate-Space - The window will be iconified. (see Iconify) 6.8 Command Line Parameters for zControl ---------------------------------------- While starting zControl as a program, you can hand over parameters. Presently the command line is only searched for names of CPX modules. If the module is found, it will be activated. zControl also accepts deactivated modules, with the file ending CPZ. 6.8.1 Anwendung anmelden It is recommended that you announce zControl as application for the file extension '*.CPX'. On the Atari desktop you can do this by selecting the program and selecting 'Anwendung anmelden' in the menu. You enter the extension 'CPX' for the program. You have to save this adjustment through selecting 'Arbeit sichern' in the menu. If you now double click on a CPX file, zControl will be activated and the CPX file will be activated. Through this, you have the option to put some CPX modules as icons on the desktop and having them activated directly by double clicking. With the desktop replacement 'Gemini' you can activate the option 'Versteht VA_START-Meldung' in the dialog 'Anwendungen...'. If zControl is already started and you request a CPX module, Gemini hands the name of the module via a VA_START message. Hint: You can make an empty file with the extension .CPX which you can use for activating zControl. My dummy file for example is named _CALL.CPX and has the size of 0bytes. This file lies as an icon on my desktop. A double click on this file activates zControl if used as an ACC. 6.8.2 AV Protocol zControl knows the VA_START message of the AV protocol. The name of the CPX module will be the parameter. If the module is loaded, it will be activated. If not, zControl will try to load it. zControl also knows the VA_DRAGACCWIND message. In Gemini you can drag a CPX file to the window of zControl. This works like Drag&Drop. 6.8.3 Drag&Drop zControl knows the Drag&Drop protocol. If you have a operating system which is capable of Drag&Drop, you can drag a CPX file from the desktop and drop it onto the window of zControl. After that, zControl will load the module and activate it. The following TOS compatible operating systems are capable of the Drag&Drop protocol: ∙ MultiTOS with an AES >= 4.1 ∙ MagiC! 3.0 ∙ MagiCMac (on the Apple Macintosh) 6.9 Iconify ----------- Iconify means the reduction of a normal GEM window to the minimal size. The window then is very small and shows a symbol in it, not the original contents. If you have many opened windows, it sometimes is comfortable to get some of the windows out of the way. zControl knows two different ways of Iconify: ∙ MultiTOS-Iconify Under MultiTOS you have an iconify button on the right top of the window. If you klick on that, the window will be iconified. ∙ ICFS-Iconify If no operating system with Iconify capability is found and the Iconify-Server (ICFS) is present, you get the Iconify via ICFS. If you click on the close button of the window and hold down one of the keys - Control - Shift - Alternate the window will be iconified. You can initiate the Iconify via keyboard via Control-Alternate- Space. This means to hold down the Control and the Alternate keys and then press Space. 7 The INF File ============== zControl saves his configuration in the file ZCONTROL.INF. This file will be searched at startup. Presently there are the following parameters: ∙ The path from where the CPX modules will be loaded. ∙ How many CPX module entries will be displayed on the main dialogue. ∙ The positions of the main dialogue window. ∙ The positions of the CPX windows. All parameters will be saved if you choose the button 'Save' in the dialog 'Options/Settings...'. 7.1 Debug Function ------------------ Sometimes there might be a problem with a CPX module. If you have many modules, you need to find out which one makes the trouble. For this purpose, you can activate a simple debug function. If you add the line DEBUG = STDOUT by hand to the INF file, you get some information form every module loading. By this you might find out where the problem is. 7.2 Where will the INF file be searched? ---------------------------------------- zControl looks for the INF file with it's configuration in different places. The sequence is as follows: 1. By using shel_envrn(), the variable HOME will be searched. 2. The environment handed over while starting the program will be searched for the variable HOME. 3. By using shel_read(), the start path will be looked for. 4. argv[0] will be examined for the start path. 5. The boot devide will be determined by _bootdev. The file will be searched on the root directory of that drive, normally C:\. As soon as one of the methods finds a path, this path will be used for loading and saving the INF file. It is recommended to use the HOME variable. In future there will be more programs that will use this variable. For the operating system MagiC (or Mag!X) you can create the HOME variable through adding the following line into the file MAGX.INF: This line should be before the #_CTR line. Under MultiTOS you can create the HOME variable through adding the following line to the GEM.CNF file: setenv HOME=c:\gemini2\user 8 Undocumented Functions ======================== XControl has at least two undocumented functions. These functions should not be used by normal CPX modules, but some modules unfortunately use them. Presently only the documented functions are supported. Following is a list of some modules that I know which use undocumented functions. 8.1 KONFIG.CPX -------------- There is a CPX module from Atari, named KONFIG.CPX. This module is used for the configuration of CPX headers, you can change the colors of the icons and the texts. This module uses undocumented functions of XControl. This leads to a crash of the system if used with zControl. That is why this module would not run under zControl. The program refuses to activate this module - you get an error message. 8.2 LINK_CPX.CPX ---------------- This module form Richard Kurz uses also undocumented functions of XControl. But it doesn't lead to a system crash. But be careful with this module. 8.3 DFREE.CPX ------------- This module from Andreas Mandel uses a undocumented function (reserve2()), I don't understand why. A The Format of the INF File ============================ zControl uses the following key words in the configuration file: ∙ CPX_PATH This parameter determines, from which folder the CPX modules will be loaded from. ∙ ANZ_DISP_ENTRY This entry determines, how many CPX modules will be displayed in the main dialogue. Presently you can have four to twelve entries. ∙ COUNTRY This entry determines the language used by zControl. ∙ WIND_MAIN This saves the position of the zControl window. The window will be opened at this position after startup. ∙ WIND_CPX? Behind this entry, the position of a CPX window will be saved. Instead of the question mark there will be the number of the window, for example 'WIND_CPX2' for the second CPX window. ∙ DEBUG See Debug Function. ∙ SINGLELOAD If the line SINGLELOAD = TRUE appears in the INF file, zControl loads all CPX, even if you run it as an ACC under Single-TOS. This option is needed for testing, if zControl is running on your computer. This option is only for those, who run zControl as an ACC under Single-TOS! B The Format of the FILESORT.SYS file ===================================== Running under TOS the CPX modules are loaded in a fixed sequence. Usually this is the same sequence in that the files were copied into their folder. If you want to change the sequence of the modules, you have to copy them by hand in the right sequence. The order in which the modules are loaded is the same order in which they will be shown in the control panel. Under MagiCMac on the Mac this is not working. The modules will be loaded in alphabetical order. That is quite nice, but not really what you want. This is why I created a new way. If zControl finds a file FILESORT.SYS in the same folder as the CPX modules, this module will be evaluated. In every line of this file there is one name of a module, without path. While loading the modules, zControl will first of all try to load the modules in the sequence given by this file. If a module in this list is not found, there will be no error message. After evaluating the file FILESORT.SYS the remaining CPX modules will be loaded. By this, you can define the sequence of the modules, at least the first ones. I know that this procedure is not really easy, you have to edit this file by yourself. But it is very flexible. The idea is to make it a lot easier by letting zControl create this file. Right now, you can create or edit this file with any ASCII editor by hand. C Sources of supply =================== Registered users can get the latest version from the author by sending a self addressed and stamped envelope with a formatted disk to the author. Non registered users should add the Shareware fee of DM10. If you have a modem, you can get the latest version of zControl in my home BBS called 'Maus Offenbach 2': ∙ Maus OF2: +49-6103-921170 The file name is ZCONTROL.LZH. The latest version will be announced in the MausNet newsgroup "ATARI.NEWS". D Thanks ======== I want to thank some people, without their help zControl would never got such a nice program. Ok, it was me who had all the coding work, but some good ideas and informations came from them. Many thanks to... ∙ *Dirk Haun @ WI2* for his information and the attentive testing. ("Na wer sagt's denn, es hat sich ja doch einer gefunden, der einen XControl-Clone schreibt") ∙ *Julian Reschke @ WI2* for his information about the Drag&Drop and all this modern stuff... ∙ *Martin Osieka @ OF2* for his help with several problems. A special thanks belongs to him for the idea on how to make several CPX modules work at the same time! Such an information scientist is sometimes really helpful - I can recommend that! ("Bitte nicht jeden Tag eine neue Release") ∙ *Rainer Wiesenfeller @ RS* for the promised beer, if I will get it some time. ("... finde ich es gut, daß sich mal jemand die Mühe gibt, dieses Programm neu zu programmieren und zu pflegen.") ∙ *Reiner Rosin @ WI2* who agreed that I use his file directory in the MAUS WI2 for zControl. It wasn't voluntary, but I don't mind... ;-) ∙ *Rene Bartholomay @ OL* who used the possibility to be the first registered user of zControl. ;-) ("Endlich mal jemand, der auch an die Großbildschirmbenutzer denkt!") E Troubleshooting ================= *Not enough memory under MagiC* Sometimes zControl reports that you don't have enough memory to load all modules, even if you have plenty of memory. While booting, if a program reserves all the memory it finds, this can happen. The memory will be available later. Under MagiC you can prevent this, through deleting the line with #_TSL of your file MAGX.INF. The multitasking will be startet by the MagiC CPX module. F History ========= ∙ *Version 0.23* - The function cpx_getcookie() now should really work. I didn't compile the corrected code. ∙ *Version 0.22* This is a beta version, for testing only. - Now you can drop deactivated modules (those with the file ending CPZ) on zControls window. It will start the module. The file ending will not be changed. - It came like always: I changed only a small part and made a big mess. The version 0.21 was not really running. I mixed up the window management. - Removed the beta-sign in the menu entry as ACC. The English TOS had a display problem with that. - If you deleted or renamed a file after booting zControl and then tried to activate it, you got some bombs. Now you get an error message and the module will be deleted from the list. ∙ *Version 0.21* - zControl now can be switched in its language. Right now you can use English and German. - Iconified modules no longer get mouse clicks and keys. - CPX-Modules now get the following messages: AP_DRAGDROP and VA_START - The function cpx_getcookie() had an error. That is now fixed. - The time-display had a minor bug. Fixed it. ∙ *Version 0.20* - The first public version of zControl.